Overview

Thank you for maintaining pycortex—i found it to be an invaluable tool for visualization of cortical data.

Please consider this PR that offers an extension the the flattening modes (+notebook, +docs, +video). Please provide your feedback and I will be happy to adjust the modification. Thank you!

cc @cmcneil @tysonnsa.

Why

1. While freesurfer mode has been used for a long time, it lacks debuggability and may require a number of iterations and a degree of patience in order to get things working. The new mode is added to timebox the flattening process by making it faster and more predictable by leveraging UV unwrap preview in Blender. This PR adds a 3rd mode of flattening that is based on Blender's UV unwrap. This mode will reduce time to flatten while producing decent quality unwraps.
2. Outdated dependencies. As I've been spinning up my flattening workflow, I kept running into dependency issues around Python, Blender, FreeSurfer with impacts ranging from just breaking to hard to debug symptoms. This PR fixes some of those and adds a new mode of flattening that relies on Blender over freesurfer.

What

• Implemented flattening logic that uses conformal UV unwrap in cortex.blender.blendlib.py. It follows the same selection as for the volume mesh. This is accessible via write_flat_patch.
  • To avoid confusion between the new flat patch write_flat_patch and the old one, renamed save_patch into write_volume_patch.
  • Renamed _get_pts_edges into _get_geometry for clarity. Added clarifying logging and elapsed time tracking. Extended docstring.
• Fix for Python 3.13+: allow blender access Python site directory to search for mda_xdrlib that was removed from Python 3.13.
• Refactored cortex.blender._call_blender to support non-code calls to Blender to reduces confusion and improves code clarity. Refactored fs_cutintofs_cut_initand added a newfs_cut_open` to improve clarity. Extended docstring.
• Rewrote cut_surface for clarity. Onboarded to recache flag to support forced generation.
• Record a tutorial video walking users through the process of cutting. Should follow the gallantlab.org approach to cutting.
• Add python notebook for the end-to-end rendering of fMRI.
• Update docs with the guidance.
  • Fixed the existing docs confusing ” and " which may result into code examples not running properly.
  • Retrofilled docs for some of the existing methods.
• Address the PR feedback.

Tutorial video

As different labs may approach cuts slightly differently, created and edited a tutorial video instruction that follows the style of gallantlab.org. The used anatomy was taken from Horikawa, T., Cowen, A. S., Keltner, D., & Kamitani, Y. (2020). The neural representation of visually evoked emotion is high-dimensional, categorical, and distributed across transmodal brain regions..

Docs update

Added a new section on the cuts. When rendered looks as follows: